Input handling utilities including image/video tracking and file mention parsing.
Characters allowed in file paths.
Includes alphanumeric, period, underscore, tilde (home), forward/back slashes (path separators), colon (Windows drive letters), and hyphen.
Pattern for extracting @file mentions from input text.
Matches @ followed by one or more path characters or escaped character
pairs (backslash + any character, e.g., \ for spaces in paths).
Uses + (not *) because a bare @ without a path is not a valid
file reference.
Pattern to detect email-like text preceding an @ symbol.
If the character immediately before @ matches this pattern, the @mention
is likely part of an email address (e.g., user@example.com) rather than
a file reference.
Pattern for highlighting @mentions and /commands in rendered
user messages.
Matches either:
/help)@file mentions anywhere in the text (e.g., @README.md)Note: The ^ anchor matches start of string, not start of line. The consumer
in UserMessage.compose() additionally checks start == 0 before styling
slash commands, so a / mid-string is not highlighted.
Accepted values for the kind parameter in MediaTracker methods.
Pattern for image placeholders with a named id capture group.
Used to extract numeric IDs from placeholder tokens so the tracker can prune stale entries and compute the next available ID.
Pattern for video placeholders with a named id capture group.
Used to extract numeric IDs from placeholder tokens so the tracker can prune stale entries and compute the next available ID.
Extract @file mentions and return the text with resolved file paths.
Parses @file mentions from the input text and resolves them to absolute
file paths. Files that do not exist or cannot be resolved are excluded with
a warning printed to the console.
Email addresses (e.g., user@example.com) are automatically excluded by
detecting email-like characters before the @ symbol.
Backslash-escaped spaces in paths (e.g., @my\ folder/file.txt) are
unescaped before resolution. Tilde paths (e.g., @~/file.txt) are expanded
via Path.expanduser(). Only regular files are returned; directories are
excluded.
This function does not raise exceptions; invalid paths are handled internally with a console warning.
Parse a paste payload that may contain dragged-and-dropped file paths.
The parser is strict on purpose: it only returns paths when the entire paste payload can be interpreted as one or more existing files. Any invalid token falls back to normal text paste behavior by returning an empty list.
Supports common dropped-path formats:
file:// URLsParse dropped-path payload variants through one entrypoint.
Parsing order is:
parse_pasted_file_paths)parse_single_pasted_file_path)extract_leading_pasted_file_path)Return whether a payload has the shape a terminal uses for a file drop.
Terminals deliver a dragged file as an absolute path (POSIX or Windows
drive/UNC), a ~/ path, or a file:// URL, so requiring that shape keeps a
payload that begins with a hand-typed relative path (assets/logo.png)
from being mistaken for a drop. Without this guard parse_pasted_path_payload
would resolve such a token against the working directory, and a caller that
rejects drops would swallow ordinary text. The check is leading-token only:
once the first token passes, later relative tokens still resolve against the
working directory.
Pure string inspection, so callers can apply it on the event loop to decide whether the filesystem-touching parse is worth a thread hop at all.
Return resolved file paths from a payload that looks like a file drop.
Applies parse_pasted_path_payload — the same parser the chat input's drop
handling uses, which only resolves paths that exist on disk — behind a shape
guard that requires the drop form terminals actually emit (see
looks_like_dropped_payload). Text-only inputs use this to detect a
dragged file so it can be rejected instead of inserted as a path.
Leading-path-plus-trailing-text payloads (<path> what is this?) are
deliberately out of scope: allow_leading_path stays off, matching the
chat input's own drop-time calls, which handle that shape later at submit
time instead.
Parse and resolve a single pasted path payload.
Unlike parse_pasted_file_paths, this helper only accepts one path token
and is intended for fallback handling when a paste event carries a
single path representation.
Extract and resolve a leading pasted path token from input text.
This is used for submit-time recovery when a user message starts with a path token followed by additional prompt text.
Normalize pasted text that may represent a single filesystem path.
Supports:
file:// URLs